Montage is a general astronomical image toolkit with facilities for reprojection, background matching, coaddition and visualization. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.
Montage source code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI ("pip install MontagePy"). See http://montage.ipac.caltech.edu/ for more information.
MontagePy.main modules: mBgExec¶
A large percentage of the Montage modules focus on processing a set of images (often retrieved from a mission archive); projecting them to a common frame, adjusting their background levels as a set, and coadding them into a mosaic.
Starting with archive access, this mosaicking sequence uses the following modules:
- mHdr — Make a template FITS header for a region.
- mArchiveList — Identify archive images for the region.
- mArchiveGet and mArchiveExec — Retreive archive images individually or as a set.
- mImgtbl — Mine a set of images for metadata (and in particular sky coverage).
- mCoverageCheck — Subset an image list based on a region specification.
- mMakeHdr or mHdr — Make a template FITS header bounding a set of images or the header for a sky region.
- mProject / mProjectPP / mProjectQL and mProjExec — Reproject images individually or as a set.
- mOverlaps — Determine which images in a set overlap each other.
- mDiff/mFitplane and mDiffFitExec — Fit the differences between images one pair at a time or all the differences.
- mBgModel — Model a set of differences to determine the "best" background correction for each image.
- mBackground and mBgExec — Background-correct an image or a set of images.
- mAdd — Coadd reprojected (and background corrected) images into a final mosaic.
This page is focused on the details of one of these modules: mBgExec. For a broader context, please see Building a Mosaic with Montage or the one shot version if you just want to see the commands.
Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.
from MontagePy.main import mBgExec, mViewer
help(mBgExec)
mBgExec Example¶
If we coadd a set of reprojected 2MASS images after reprojection but without doing anything about the backgrounds, the differences in background levels are obvious:
from IPython.display import Image
mViewer('-color black -imginfo M17/rimages.tbl \
-ct 1 -gray M17/uncorrected.fits -2s max gaussian-log \
-out work/M17/uncorrected.png',
'', mode=2)
Image(filename='work/M17/uncorrected.png')
Through the background modeling, we can derive a set of corrections to the individual images (the "id" in this table is a reference to the images metadata table shown as an overlay above).
import pandas as pd
from astropy.io import ascii
ipactable = ascii.read('M17/corrections.tbl').to_pandas()
ipactable
With mBgExec, we can apply these corrections to the original image:
rtn = mBgExec('M17/projected',
'M17/pimages.tbl',
'M17/corrections.tbl',
'work/M17/corrected')
print(rtn)
and after coadding the corrected images together, we get:
mViewer('-color black -imginfo M17/rimages.tbl \
-ct 1 -gray M17/mosaic.fits -2s max gaussian-log \
-out work/mosaic_bgexec.png',
'', mode=2)
Image(filename='work/mosaic_bgexec.png')
Montage functions return JSON structures. They always include a status (0: success; 1: error) and a variable number of informational parameters.
mBgExec Error Handling¶
If mBgExec encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.
For instance, if the user asks for an invalid file:
rtn = mBgExec('M17/projected',
'M17/unknown.tbl',
'M17/corrections.tbl',
"work/M17/corrected")
print(rtn)
Classic Montage: mBgExec as a Stand-Alone Program¶
mBgExec Unix/Windows Command-line Arguments¶
mBgExec can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mBgExec [-p projdir] [-s statusfile] [-d] [-n(o-areas)] images.tbl corrections.tbl corrdir
If you are writing in C/C++, mBgExec can be accessed as a library function:
/*-*****************************************************************/ /* */ /* mBgExec */ /* */ /* Take the background correction determined for each image and */ /* subtract it using mBackground. */ /* */ /* char *path Path to images to be background-corrected */ /* char *tblfile Table file list of images to correct */ /* char *fitfile Table of background levels/slopes */ /* char *corrdir Directory for corrected images */ /* int noAreas Flag indicating there are no area images. */ /* int debug Debug flag. */ /* */ /*******************************************************************/ struct mBgExecReturn *mBgExec(char *path, char *tblfile, char *fitfile, char *corrdir, int noAreas, int debug)
Return Structure
struct mBgExecReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
int count; // Number of images
int nocorrection; // Number of images for which there was no correction
int failed; // Number of images where correction failed
};